(check often)
WEB FM 1.3 Documentation
WEB FM is a common gateway interface (cgi) for linking FileMaker® Pro databases with StarNine Technologies' WebSTAR® world-wide web server software for Macintosh®.
WEB FM allows you to quickly and easily put a web interface on your existing FileMaker Pro databases, or add form and database processing features to your existing web broadcasting station.
Table of Contents
WEB FM supports most FileMaker Pro database operations using a web browser, including Find, Find All, Sort, New Record, and the modifying of records.
WEB FM supports the simultaneous broadcasting of more than a dozen FileMaker Pro databases from a single Web Station.
WEB FM supports any number of html fill-out forms for finding or adding records to a FileMaker Pro database. This is possible because all variables used by WEB FM are contained in the html fill-out form itself. This even includes custom headers and footers for "hit lists" of found records.
WEB FM faithfully transfers fill-out form field attributes such as checkboxes and radio buttons to the targeted FileMaker Pro database. For example, submitting the contents of an input field of type checkbox with multiple selections will appear in the corresponding FileMaker Pro database field as selected checkbox items.
WEB FM supports commands invoked by an html anchor rather then a fill-out form.
WEB FM supports input fields that contain html.
Search a FileMaker Pro database field in as little as 2-3 seconds!
Create a new record in a FileMaker Pro database in as little as 5 seconds.
Easily handle a half-dozen simultaneous database requests!
WEB FM makes it easy to query or add to a FileMaker Pro database, because WEB FM does NOT require any cgi programming! All variables used by WEB FM are contained in the html fill-out form itself. For example, when designing a web form to add new records to a FileMaker Pro database, simply make sure that the name of each input field on the form exactly matches a field name in the target FileMaker Pro database.
WEB FM requires an understanding of how to build a FileMaker Pro database, complete with calculation fields, and the basics of programming an html fill-out form.
WEB FM requires WebSTAR v1.2 or greater! WEB FM does NOT currently work with MacHTTP!
WEB FM requires FileMaker Pro 2.1v3 or greater!
WEB FM requires 1MB of available system memory.
WEB FM expects the target FileMaker Pro database to already be open.
WEB FM works best with WebSTAR running as the FOREGROUND application.
WEB FM requires AppleScript and the Thread Manager (Included with WebSTAR)
Drag the "WEBFM" folder into the same folder that you have the WebSTAR application.
WEB FM requires that you configure WebSTAR with a user-defined action. User-defined actions are WebSTAR instructions to run an external application, in this case "FM.acgi", which is invoked based on a URL's suffix only. For additional information on defining "User-Defined Actions", please refer to section 3.4 in the documentation that comes with WebSTAR.
Use the WebSTAR Admin utility to connect with the WebSTAR server. WebSTAR must already be open on the web server and program linking (sharing control panel) must be turned on. Select "Actions..." from the Configure menu, and update the WebSTAR server as shown below.
Next, select "Suffix..." from the Configure menu and update WebSTAR as shown below. A common mistake when doing this is not clicking "Add" and then the "Update" button.
If you do the WEB FM Installation now, you can use the sample html forms in the Available Commands section to query or add records to the example "hotlist.fm" FileMaker Pro database. To do this you should access the "docs.html" file over the net by entering a URL similar to http://192.0.1.2/webfm/docs.html. You should also open the "hotlist.fm" FileMaker Pro database found in the "hotlist" folder.
It's a good idea to name the FileMaker Pro application exactly "FileMaker Pro".
This section explains how to program an html fill-out form with commands that WEB FM will understand. All variables for customizing the behavior of WEB FM are entered in the html fill-out form itself.
The name of the target FileMaker Pro database to act upon is specified as part of the URL. The database does not actually have to reside in this URL location, and in fact can actually exist outside the root WebSTAR application folder. Nevertheless, WEB FM does expect the target FileMaker Pro database to already be open.
In the example URL below, "hotlist.fm" is the database name:
<FORM METHOD="POST" ACTION="/hotlist.fm$SEARCH">
The database name MUST end with the ".fm" suffix! This suffix on the URL tells WebSTAR to pass the connection onto the program "FM.acgi" for processing. The actual FileMaker Pro database itself can optionally have the ".fm" suffix in its name, but it's not necessary.
It's a good idea, although not required, to name your FileMaker Pro database succinctly. If your FileMaker Pro database has two or more words in it's name, in the URL simply replace any spaces with a "+" character. Also, be careful about using odd or off-limit characters such as "/","#","< >", etc. in your database name.
WEB FM supports most FileMaker Pro database operations using a web browser. WEB FM expects to receive a command to perform in the direct parameter, which is the text in a URL immediately following a "$" symbol but preceding, if any, the "?" symbol. The POST method, unless specified otherwise, is the recommended method for submitting fill-out forms.
SEARCH is the recommended command for searching a FileMaker Pro database. Using the SEARCH command in a fill-out form packages all query field values into a single search string. You can then have several fields contribute to a single search string. This can be useful when searching for a range of numbers or dates. The fields, for example, might be of type hidden or have checkbox or radio button attributes. You can only search a single field in your FileMaker Pro database using the SEARCH command, so WEB FM uses the words in this single search string to find all matching records. Most likely the database field to search is a calculation field that combines the various individual fields into one big search field.
The SEARCH command requires that a form input field exist with a name of "field". The default result of using this command is an unordered list of records returned to the client browser. The list of found records returned should be from a calculation field with "<LI>" or other seperator tags. You may override the various default settings by using optional fields (normally of type hidden) in your form. Below are optional fields which, when needed, should be added to forms that use the SEARCH, QUERY, or FIND commands. Please view the source html on the example hotlist html files for examples of using these parameters.
<INPUT TYPE=HIDDEN NAME="header" VALUE="">
<INPUT TYPE=HIDDEN NAME="footer" VALUE="">
<INPUT TYPE=HIDDEN NAME="sort" VALUE="">
<INPUT TYPE=HIDDEN NAME="max" VALUE="">
<INPUT TYPE=HIDDEN NAME="doscript" VALUE="">
<INPUT TYPE=HIDDEN NAME="html" VALUE="">
Modify the value of the SORT field with the name of the field in the database you wish to sort on. NOTE: Sorting records will significantly add to the time required to return search results to the client browser. A better approach may be to use the doscript variable to execute a ScriptMaker script to highly customized the sort order.
Modify the value of the MAX field with a number equal to the maximum number of records to return to the client browser. It's not recommended to include this parameter because it just adds to the complexity of processing the request. Do experimentation to determine if you really need to use the MAX variable. WEB FM can easily return a simple list of hundreds of found records.
Modify the value of the HTML field with the name of the field in the database you wish to return to the client browser. The default is to return a database field with a name of "html".
WEB FM allows for custom formatting of headers and footers when returning a list of found records. This can be helpful, for example, when you wish to return a list of records formatted as a table rather then an unordered list. Use the "header" field of type hidden to create your own header and override the default.
IMPORTANT -- Encode all occurrences of special characters such as "<" or ">" to their ASCII equivalent, or escape these characters by using HTML character entities ("<" = & lt, ">" = & gt, no space between & and lt or gt). Copying your header html to a word processor with a search and replace feature works well when you need to do encoding. Likewise, there is an encode URL OSAX available on the net for doing encoding. You will likely have to encode even the "=" character.
For the location in the header you wish the total number of records found to be displayed, simply enter the word "FOUNDRECORDS" in your custom html header. Here are additional words which get replaced when included in your custom header:
- SEARCHSTRING
- FOUNDRECORDS
- TOTALRECORDS
- CURRENTDATE
The QUERY command is useful when you wish to search multiple fields in a target FileMaker Pro database using an "OR" criteria. QUERY is equivelant to a Find in FileMaker Pro with multiple requests. The QUERY and FIND commands require that all fields in the html form (other then variable fields) have names that exactly match the field names in the FileMaker Pro database. Entered values for these fields become the search string for each field.
The QUERY and FIND commands require a form input field exist with a name of "html" and a value equal to the name of the field in the database to return as html to the client browser.
In the example URL below, QUERY is the command to perform.
The FIND command is useful when you wish to search multiple fields in a target FileMaker Pro database using an "AND" criteria.
Searching multiple fields is significantly slooower then searching only one field. This is why the SEARCH command is recommended, whenever possible, for most database searches. Refer to the SEARCH command for additional information on custom formatting of headers and footers when returning a list of found records.
The FINDALL command returns every record from the target database. All variables for this command are normally declared as part of the URL, but may also be declared in a fill-out form using the GET method. In the example URL below, "html" is the field name in the database with html to return.
The FINDSET command returns every record from the target database having a specified value. All variables for this command are normally declared as part of the URL, but may also be declared in a fill-out form using the GET method.
The FINDUSER command returns a single FileMaker Pro record if, and only if, the user enters a username and password in the User Authorization dialog box which exists in the database. This command can be used very nicely to present an update form only when the user knows the correct username and password.
The RETRIEVE command is used to retrieve a single cell value from one record in a FileMaker Pro database. This command is normally used for getting detailed information from a list item previously returned from a database search. In the example URL below, "retrieve" is the field name in the database with html to return. This field should be a calculation field in the FileMaker Pro database that combines and formats other fields into proper html. WEB FM expects the calculation field to generate all the html, including the html tag for window title. In most situations, the value variable should be a unique value found in the database, and the database search field should be formatted as a number if the search value is a number.
The RANDOM command returns a random record from the target FileMaker Pro database. In the example URL below, "retrieve" is the field name in the database with html to return. WEB FM expects the calculation field to generate all the html, including the html tag for a window title.
Use the ADD command to create new records in the target FileMaker Pro database. The ADD command requires that ALL fields in the html form have names that exactly match field names in the target FileMaker Pro database. No particular field order is required.
The ADD command will properly handle input fields that contain html rather then normal text.
The ADD command faithfully transfers fill-out form field attributes such as checkboxes, radio buttons, and scroll lists to the targeted FileMaker Pro database.
On a successful ADD, you may optionally specify the field name in the database with html to return. To do this include an input field on your form with a name of "html" and a value equal to the field name in your database. The doscript command will also work in this same way.
The UPDATE command is equivalent to the ADD command, only a new record is not created in the FileMaker Pro database. Also, the UPDATE command generally requires a "username" field and "password" field on the form. The username field doesn't have to contain a username, but could contain a unique serial number instead. Only input fields submitted with an actual value get updated. This means you cannot replace text in a database cell with nothing.
The DELETE command does just that, it deletes a record from the database that matches the submitted username and password value. The DELETE command generally requires a username field and password field on the form.
Mailing lists are your best source for getting help with WEB FM. Feel free to tap the collective minds of other WEB FM users on either the FMPRO-CGI mailing list (http://www.blueworld.com/lists/fmpro-cgi/) or the WEBSTAR-TALK mailing list (http://www.starnine.com/webstar/mailinglist.html).
If you need additional WEB FM support, send email to support@macweb.com.
If you wish to locate a consultant to help implement WEB FM, refer to the Mac Web Consultants Directory.
Be sure to subscribe to the announcements only WEB FM mailing list. Information on subscribing is available at the WEB FM Home Station.
Serving a database on the Internet puts it at great risk. Therefore, care should be taken before using WEB FM and broadcasting an important database. If your database does not require adding or updating records, then setup your database in FileMaker Pro to open with read access only.
Make frequent backups of any and all FileMaker Pro databases broadcast on the Internet.
There are a number of fields that every FileMaker Pro database broadcast on the Internet should have. The most important of which is a field with name "password". Without this field people can update and delete records in your database at will. Existence of a password field in the database enables password protection on a record by record basis.
NOTE: Returning a database field with name "password" to a web browser has been disabled.
One nice feature of WEB FM that is particulary useful for updating database records is specifying an html document rather then a cell value to return. When finding a record, in the "html" parameter just enter the file name relative to the current URL. Moreover, including the names of database fields in this html document with the proper tag will tell WEB FM to replace this tag with the cells' value from the database. The proper tag is to include the field name in the html document with the *symbol* on both sides. Use this feature with caution and only after thoroughly testing it. After clicking the link below, in the authorization dialog that appears enter "2" for the username and "WEB FM" for the password.
<FORM METHOD="POST" ACTION="/webfm/hotlist/hotlist.fm$FINDUSER?html=update.html">
Including a field with name "doscript" in your html form or URL will tell WEB FM to run a ScriptMaker script using the doscript value as the script name. Use carefully! WEB FM waits for the script to complete before returning a cells value to the web browser.
- Fields that most FileMaker Pro databases should probably have include:
- NUMBER
- USERNAME
- PASSWORD
- HTML
- ADD
- RETRIEVE
- WEB FM relies extensively on the use of FileMaker Pro calculation fields. This reliance, however, allows for ease and flexibility in creating dynamic, on-the-fly html.
- When constructing an html calculation field, it's a good idea to work on a copy of your database with just a small sample of records. Editing a calculation field again and again to get proper html can be time consuming when the database is large. To create a small duplicate database, select Save A Copy from the File menu in FileMaker and select the option for Clone. Find a small sample of records in your original database. Open the Clone, and then import the small sample of records from the original database into the Clone.
- When defining a calculation field to be used in querying a database, be sure to include a space character between each field in the calculation. This will ensure that words from different fields do not join together.
- You should turn FileMaker Pro's curly quotes feature off for every database you wish to serve on the web. Web browsers do not display curly quotes in an html page well. Open your FileMaker Pro database and select Preferences from the File menu. The Document preference has an option for turning curly quotes off.
- If you wish to use a single password to update any record in a FileMaker Pro database, create a password field that auto-enters the same password for each new record.
- Likewise, create a number and/or username field that auto-enters a unique serial number for each new record (format the field as a number, not text). Use this unique field for retrieving a single record from the database. If you have an existing database that needs a unique value entered for each record, the Replace... command from the Edit menu will allow you to do this quickly. Refer to the FileMaker Pro manual for instructions.
- With a little effort the SEARCH command, with it's ability to bundle form values into a single string, can be used to do exact, less then, greater then, or range searches. Refer to FileMaker Pro's symbol menu in FIND mode for available symbols.
- The UPDATE, DELETE, and FINDUSER commands are still undergoing considerable refinement. Be prepared to alter your implementation of these commands with additional releases of WEB FM.
WEB FM is a commercial cgi with commercial features and performance. A fully functional (but time-limited) evaluation copy of WEB FM can be found at the WEB FM Home Station.
WEB FM is a product of the Web Broadcasting Co. (WBC). For up-to-date pricing and ordering information, please see the WEB FM Home Station.
WEB FM Order Form
Special thanks goes out to a number of people for helping to make WEB FM a reality!
Brad Schrick for his insightful comments, help, and coining the WEB FM name!
Chuck Shotton for his vision in developing the first Macintosh web server, MacHTTP!
Russell Owen for kindling the fire by making his personal FileMaker cgi available to others!
Wayne Walrath for developing key webmaster utilities like his ACME Script Widgets!
Copyright © Eric Bickford 1995 All Rights Reserved.
WEB FM is a trademark of Eric Bickford and the Web Boadcasting Company
ACME Script Widgets Copyright © 1994-1995 Wayne Walrath, all rights reserved
FileMaker is a registered trademark of Claris Corporation
WebSTAR is a registered trademark of Starnine Technologies
Macintosh is a registered trademark of Apple Computer Inc.
11/6/95